home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem9.asc < prev    next >
Text File  |  1987-10-10  |  21KB  |  449 lines
  1.                         *PROFESSIONAL GEM*
  2.                            By Tim Oren
  3.             Column #9 - VDI Graphics: Lines and Solids
  4.  
  5.      This  issue  of ST PRO GEM is the first in a  series  of  two
  6. which  will explore the fundamentals of VDI graphics  output.   In
  7. this installment, we will take a look at the commands necessary to
  8. output simple graphics such as lines,  squares and circles as well
  9. as  more complex figures such as polygons.   The following episode
  10. will  take a first look at graphics text output,  with an emphasis
  11. on  ways  to  optimize its drawing speed.   It will  also  include
  12. another  installment  of ONLINE Feedback.   As usual,  there is  a
  13. download  with  this column.   You should find it under  the  name
  14. GEMCL9.C in DL3 of ATARI16 (PCS-58).
  15.  
  16.                         A  BIT  OF HISTORY
  17.  
  18.     One  of  the reasons that the VDI can  be  confusing  is  that
  19. drawing anything at all,  even a simple line,  can involve setting
  20. around four different VDI parameters before making the draw  call!
  21. (Given  the state of the GEM documents,  just FINDING them can  be
  22. fun!)  Looking backwards a bit sheds some light on why the VDI  is
  23. structured this way,  and also gives us a framework for organizing
  24. a discussion of graphics output.
  25.  
  26.      The GEM VDI closely follows the so-called GKS standard, which
  27. defines  capabilities  and calling sequences  for  a  standardized
  28. graphic  input/output system.   GKS is itself an evolution from an
  29. early system called "Core".   Both of these standards were born in
  30. the  days  when  pen plotters,  vectored  graphics  displays,  and
  31. minicomputers  were  the  latest items.   So,  if you  wonder  why
  32. setting  the drawing pen color is a separate command,  just  think
  33. back  a  few  years when it actually meant  what  it  says!   (The
  34. cynical   may   choose   instead  to  ponder   the   benefits   of
  35. standardization.)
  36.  
  37.      When  doing  VDI  output,  it helps if you pretend  that  the
  38. display screen really is a plotter or some other separate  device,
  39. which  has  its own internal parameters which you can set  up  and
  40. read  back.   The class of VDI commands called Attribute Functions
  41. let  you set the parameters.   Output Functions cause the "device"
  42. to  actually  draw  someone once it is  configured.   The  Inquire
  43. Functions let you read back the parameters if necessary.
  44.  
  45.      There  are two parameters which are relevant no  matter  what
  46. type of object you are trying to draw.   They are the writing mode
  47. and  the clipping rectangle.   The writing mode is similar to that
  48. discussed in the column on raster operations.   It determines what
  49. effect the figure you are drawing will have on data already on the
  50. screen.  The writing mode is set with the call:
  51.  
  52.           vswr_mode(vdi_handle, mode);
  53.  
  54.    (Vdi_handle,  here  and  below,  is the  handle  obtained  from
  55. graf_handle at the beginning of the program.  Mode is a word which
  56. may be one of:
  57.  
  58.           1 - Replace Mode
  59.           2 - Transparent Mode
  60.           3 - XOR mode
  61.           4 - Reverse Transparent Mode
  62.  
  63.      In  replace mode,  whatever is on the screen is  overwritten.
  64. If  you are writing characters,  this means the background of each
  65. character cell will be erased.
  66.  
  67.      In  transparent  mode,  only  the pixels directly  under  the
  68. "positive"  part  of the image,  that is,  where 1-bits are  being
  69. written, will be changed.  When writing characters, the background
  70. of the cell will be left intact.
  71.  
  72.      In XOR mode,  an exclusive or is performed between the screen
  73. contents and what is being written.   The effect is to reverse the
  74. image under areas where a 1-bit occurs.
  75.  
  76.      Reverse transparent is like transparent,  but with a "reverse
  77. color  scheme".   That  is,  only  places where a 0-bit is  to  be
  78. put   are  changed  to  the  current  writing  color.    When  you
  79. write  characters in reverse transparent (over white),  the effect
  80. is reverse video.
  81.  
  82.      The  other  common parameter is the clipping  rectangle.   It
  83. defines the area on the screen where the VDI is permitted to draw.
  84. Any output which would fall outside of this area is ignored; it is
  85. effectively a null operation.   The clip rectangle is set with the
  86. call:
  87.  
  88.           vs_clip(vdi_handle, flag, pxy);
  89.  
  90.    Pxy is a four-word array.   Pxy[0] and pxy[1] are the X  and  Y
  91. screen coordinates,  respectively,  of one corner of your clipping
  92. rectangle.    Pxy[2]  and  pxy[3]  are  the  coordinates  of   the
  93. diagonally opposite corner of the rectangle.   (When working  with
  94. the  AES,  use  of  a  GRECT to define  the  clip  is  often  more
  95. convenient.  The routine set_clip() in the download does this.)
  96.  
  97.      Flag is set to TRUE if clipping is to be used.  If you set it
  98. to  FALSE,  the  entire  screen is assumed to be fair  game.
  99.  
  100.      Normally,  you should walk the rectangle list for the current
  101. window to obtain your clipping rectangles.  (See ST PRO GEM #2 for
  102. more details.)  However, turning off the clip speeds up all output
  103. operations,  particularly text.  You may do this ONLY when you are
  104. absolutely certain that the figure you are drawing will not extend
  105. out of the top-most window, or out of a dialog.
  106.  
  107.                     THE LINE FORMS ON THE LEFT
  108.  
  109.      The  VDI  line  drawing  operations  include  polyline,  arc,
  110. elliptical  arc,  and rounded rectangle.   I'll first look at  the
  111. Attribute Functions for line drawing,  then go through the drawing
  112. primitives themselves.
  113.  
  114.      The  most  common used line attributes are color  and  width.
  115. The color is set with:
  116.  
  117.           vsl_color(vdi_handle, color);
  118.  
  119.    where color is one of the standard VDI color  indices,  ranging
  120. from  zero to 15.   (As discussed in column #6,  the  color  which
  121. actually appears will depend on the pallette setting of your ST.)
  122.  
  123.      The  line width may only be set to ODD positive  values,  for
  124. reasons  of  symmetry.   If you try to set an even value,  the VDI
  125. will take the next lower odd value.  The call is:
  126.  
  127.           vsl_width(vdi_handle, width);
  128.  
  129.      The  two  less  used line parameters are the  end  style  and
  130. pattern.   With  the  end style you can cause the output  line  to
  131. have rounded ends or arrowhead ends.  The call is:
  132.  
  133.           vsl_ends(vdi_handle, begin_style, end_style);
  134.  
  135.    Begin_style  and end_style are each words which  may  have  the
  136. values zero for square ends (the default),  one for arrowed  ends,
  137. or  two  for  rounded ends.   They determine the  styles  for  the
  138. starting and finishing ends of the line, respectively.
  139.  
  140.      The line pattern attribute can select dotted or dashed  lines
  141. as  well  as more complicated patterns.   Before  continuing,  you
  142. should  note one warning:  VDI line output DOES NOT compensate for
  143. pixel aspect ratio.  That is, the dashes on a line will look twice
  144. as long drawn vertically on a medium-res ST screen as they do when
  145. drawn horizontally.  The command for setting the pattern is:
  146.  
  147.           vsl_type(vdi_handle, style);
  148.  
  149.    Style  is  a word with a value between 1  and  7.   The  styles
  150. selected are:
  151.  
  152.           1 - Solid (the default)
  153.           2 - Long Dash
  154.           3 - Dot
  155.           4 - Dash, Dot
  156.           5 - Dash
  157.           6 - Dash, Dot, Dot
  158.           7 - (User defined style)
  159.  
  160.    The  user  defined  style is determined  by  a  16-bit  pattern
  161. supplied  by the application.   A one bit in the pattern  turns  a
  162. pixel on, a zero bit leaves it off.  The pattern is cycled through
  163. repeatedly,  using the high bit first.  To use a custom style, you
  164. must make the call:
  165.  
  166.           vsl_udsty(vdi_handle, pattern);
  167.  
  168.   before doing vsl_type().
  169.  
  170.      As  I  mentioned  above,   the  line  type  Output  Functions
  171. available are polyline,  circular and ellliptical arc, and rounded
  172. rectangle.   Each  has  its own calling sequence.   The call for a
  173. polyline is:
  174.  
  175.           v_pline(vdi_handle, points, pxy);
  176.  
  177.   Points tells how many vertices will appear on the polyline.  For
  178. instance,  a  straight  line has two vertices:  the  end  and  the
  179. beginning.   A closed square would have five,  with the first  and
  180. last  identical.    (There  is  no  requirement  that  the  figure
  181. described be closed.)
  182.  
  183.      The pxy array contains the X and Y raster coordinates for the
  184. vertices,  with a total of 2 * points entries.